Important: When updating your code from a previous version of the framework, you definitly need to make sure that you update your copy of the file "MyConfiguration.h" to include all the new configuration options. If you don't, various bits of code simply won't be compiled/included in your application!
This is particularly important in the current release for the 'kCompileWithCGINoDataHTTPError' option.
Also make sure you add new files (where appropriate) in the release to your project files! Otherwise you may be missing crucial resources or functions.
1.0 beta 16 - Monday, September 30, 1996
* Help
- New file "balloon-help.bh" contains balloon help definitions for some of the interface elements (Menus, preferences dialog)
* CGI
- New function 'CGISendData' (I think I implemented this in 1.0d15 but forgot to mention it...) This function can be used by both CGI applications (uses Send Partial) and web server plugins. Read it's header comment in the source file for full details. Be warned Send Partial support is still buggy. Fixing this is very high on my list of priorities.
- Various fixes and additions to make the code more friendly for C++ compiling. (Thanks again, Greg.)
- New function 'CGIIsSecurePath' will test a path string for known security problems, including strings that begin with or contain "//", "::" or "..".
- Added a semaphore to the 'CGIWSAPIUseMyResFile' and 'CGIWSAPIResetResFile' functions to prevent the saved res file from getting messed up.
- Changed 'cgiWSAPIDebugMessage' to actually only compile when debugging mode is on.
- Made "CGI.c" the '__MainSegment__' when compiling as a plug-in.
- Now properly set the current resource fork before calling 'CustomStartup', when compiling as a WebSTAR plug-in.
* Menus
- If you change your menus from the defaults supplied with the framework, you will need to modify the file "balloon-help.bh".
* Preferences
- New configuration options:
- 'kCompileWithPreferences': support preference handling
- 'kCompileWithPreferencesDialog': include the preferences dialog
- 'kCompileWithPreferencesFile': use an external prefs file rather than the application or plug-in's resource fork.
- "balloon-help.bh" includes balloon help for the preferences dialog. You will want to change it if you modify the dialog.
- Added (invisible) balloon help item to preferences dialog DITL in "MyInterface.rsrc".
- Cleaned up the dialog so it will be readable when displayed in Chicago 12 point.
- Fixed the dialog's "Idle time until quit" text field to actually be in seconds.
- Preference resources are now being properly released by the the framework (allowing the prefs file to close).
* String Handling
- New function 'StringNCompareNoCase' - same as strncmp except that it's case-insensitive.
* Symantec Project Manager
- Symantec users should note that I'm now using release 5 of the Symantec CD series (SPM 8.1).
- You need to make sure there's an alias to the 'grantscgi' folder in your project folder.
- TPM users are going to have lots of fun trying to get this all happening well (I recommend upgrading to SPM if you can). Most importantly, you have to move the 'grantscgi' folder into your project folder (which makes things weird when building more than one cgi). I've moved the TPM project file into the "old" subfolder within the "Projects" folder to indicate that it's not well supported now.
- For some reason the clickable url in the about box isn't working from the SPM compile. Please let me know if you figure out how to fix this.
- New function 'CGIHostNameDifferent'. Compares the "Host:" field of the 'full_request' against a given hostname string. Note that not all servers supply the 'full_request' and not all browsers supply the 'Host:'.
* Logging
- New function 'LogWriteDebugEntry'. This call should generally be used in the form:
- New menu "Options" provides user access to application settings.
- New configuration option 'kCompileWithMenuOptions' determines whether to include the Options menu (which is required if you're using the preferences dialog). Note that if you turn this off, you'll need to modify MBAR 128 in "Menus.rsrc" to not include Menu res ID 131. You will also want to delete MENU 131.
- Changed function 'startupMenus' in "Startup.c" to 'MenuStartup' in "MenuFunc.c"
* Preferences
- New configuration option: 'kCompileWithPreferencesFile'.
- New resources (type 'Pref') store preference values.
- A Preferences file (named in STR# 10001, in "MyCustom.rsrc") is now generated when user changes a setting.
- The Options menu links to the new Preferences dialog.
- If you want to add non-numeric text fields to the prefs dialog, you'll need to modify the function 'prefDialogEventFilter' to NOT trap non-numeric characters. I put the trapping in as an easy (read: lazy) way to avoid problems with users entering invalid characters.
- Note that you must set 'kCompileWithProcessFileSpec' (in "MyConfiguration.h") to 1 if you are compiling with preferences file support.
* TCP Networking
- Added basic TCP stream functions. Currently these functions only work when compiling as a WebSTAR plug-in. The plan is to also make them work using OpenTransport and MacTCP when compiling as an application. These functions can currently only be called from functions that have a valid CGIHdl (IE. those in the "MyCGIProcess.c" file).
- New configuration option 'kCompileWithTCPCode'.
* Misc
- New global variable 'gAppFileRef' is a file reference to the application resource fork.
Note: This is still a potentially unstable version - the next beta should be out within a week or two of this release.
Note: Be sure to read the notes for version 1.0 development 15 which follow immediately after these notes for 1.0 alpha 15.
Note: The Symantec project files have not been updated to support the new code yet. That update should happen in time for the 1.0 beta 15 release. My apologies for any inconvenience. In any case, the Symantec support for the WSAPI isn't available from StarNine yet.
* About Box
- Added a second param text ("^1") that is passed the 'kTargetPString' string constant which specifies the code type of the application ("PPC" or "68K").
* CGI Utilities
- Added string constant for "CONDITIONAL_GET" HTTP method. Updated the functions 'cgiWSAPIGetParamHTTPMethod' and 'cgiAEGetParamHTTPMethod'.
- Improvements to handling of Preprocessor state.
- New field in the CGIRecord (theCGIHdl): 'role'. If you include the 'action' field in your CGI (kCompileWithCGIActionSupport) the role field will be set by the new private (read: don't use this) function 'cgiSetRole'. It provides an easy way to determine what type of processing your CGI should do (CGI, PreProcessor, PostProcessor, etc.).
* Event Handling
- Modified 'doMouseDown' to handle custom dialogs better. It references the new custom function 'CustomDialogMouseDown'.
* Logging
* !!! Big changes here:
- Added WSAPI support. The function 'LogWriteEntry' is now the only log call that you can use when compiling as a WSAPI plug-in. It will put a newline character at the end of the string passed to it.
- New function 'DisplayString' displays a string to the status window (of the server if using WSAPI). Currently it does nothing when compiling as a CGI.
* QC support
More rigorous testing can be performed when QC is installed. To turn on the extra tests in the framework, do the following:
1) Add the appropriate QCAPI library file(s) to your project(s).
2) Make sure the "QCAPI.h" header is in your system (compiler) search/access path.
3) Turn on (set to 1) 'kCompileWithExtraQC' in the "MyConfiguration.h" header.
As with assertions, make sure you turn off the extra QC testing for your distribution compiles.
* Startup
- Modified function 'CustomStartup' - you should look at this again and modify your current CustomStartup functions to match the changes.
- Got rid of functions 'CustomCGIStartup' and 'CustomListSTARStartup' since their functionality is covered by 'CustomStartup'. You can keep your existing versions of these functions - just make sure that you have prototypes defined for them where needed.
* WebSTAR API (WSAPI) (these functions apply ONLY when compiling as a plug-in)
- Corrected the PPC project file to use 68K struct alignment.
- A pair of new functions: 'CGIWSAPIUseMyResFile' and 'CGIWSAPIResetResFile'. If you need to access resources in the plug-in file's resource fork, you must first call 'CGIWSAPIUseMyResFile'. You must make certain that before you return from a custom function, or make a call to ProcessGiveTime, that you call 'CGIWSAPIResetResFile'. See the section on 'Resources' in chapter 2 of the WSAPI documentation for further explanation.
- Lots of other bits were modified in "CGI.c" to accommodate the WSAPI.
* Misc
- Added 'kTargetPString' to "compiler_stuff.h". It's a pascal format string that provides a string indicating the platform of the code.
- New function "SaveJPEGFromQuickCam" grabs a QuickCam framew to a JPEG file.
WARNING: This is a development (not well-tested, probably crash-prone) release. You should not rely on the code in this release for final product. It is being released for testing purposes, and to allow users of the framework to know what changes are being made to the framework. All usual warnings about backing-up and the potential hazards of using the software go triple for this release. "Danger Will Robinson!"
* CGI Utilities
- 'CGIActionIsCGIorACGI' function should now work correctly when the CGI is used by servers other than WebSTAR.
- The function prototypes for 'CGIFormFieldsDispose' and 'CGIAESearchDoc' have been moved from "CGI.h" to "CGI.c" since they shouldn't be called outside that module.
- New configuration option 'kCompileWithCGIcontent_length'. Used for the 'content_length' parameter. New constant 'kCGIcontent_length' maps to 'CLen'. New field in the CGIRecord structure 'content_length'.
- New field in CGIRecord: 'dataSent'. Used with SendPartial (and when you send data from within custom code when using the WSAPI). Set this Boolean value to true if you return data on the connection from within your custom code.
- New configuration options ' kCompileWithCGIfileMIMEType', 'kCompileWithCGIserverField', 'kCompileWithCGIserverDirectoryPath', 'kCompileWithCGIurlPhysicalPath', 'kCompileWithCGIifModifiedSince' and 'kCompileWithCGIcurrentRealm'. These correspond to new fields in CGIRecord. These fields are only available if compiling as a WSAPI plug-in.
- New configuration option 'kMyCGIName'. Must be a unique ID for your CGI/plug-in. A good rule is to put your personal or company name followed by a dash, then the name of the CGI. For example: "GRANTNEUFELD-GRANTSCGI". This constant must not exceed 31 characters.
- Cleaned up "CGI.c" a bit. Moved most of the public functions to the top of the file, leaving the private functions at the bottom. Renamed a couple of the private functions to now have lower case beginings to better indicate that they are not really public functions.
- New configuration option: 'kCompileWithCGINoDataHTTPError'. If this is option is set, the framework will not generate an http error header if you do not set responseData in the CGIHdl. This is really only useful if you want to build a Preprocessor CGI which will need to return no data if it wishes to indicate to the server that the preprocessor did not handle the cgi event, and that that event should be passed along to normal processing.
- See the new CGI Memory functions listed in the Memory section below.
- Renamed 'cgiDisposeHandle' to 'cgiDisposeRecord' to reduce confusion.
- The functions: 'CGIFormFieldsFromArgs', 'CGIFormFieldsDispose' and 'CGIEncodeURLChars' have been changed to take a CGIHdl as their first parameter.
* Custom Functions
- All the prototypes for the custom functions (in "MyHandlers.c", "MyCGIProcess.c" and "MyListSTARProcess.c") have been moved from the various headers they were scattered amongst ("AEHandlers.h", "CGI.h", "EventUtil.h", "ListSTAR.h", "ProcessUtil.h", "Quit.h", "Startup.h" and "WindowInt.h") to the new file "CustomHandlers.h".
- 'CustomStartup' has been modified to take the wsapi 'commandPtr' when compiling under wsapi.
* Memory
- New functions 'MemoryDisposeHandle' and 'MemoryDisposePtr'. These should be used in place of the system calls 'DisposeHandle' and 'DisposePtr'.
- New functions 'CGINewHandle', 'CGINewHandleClear', 'CGINewPtr', 'CGINewPtrClear', 'CGIDisposeHandle' and 'CGIDisposePtr'. These MUST be used (instead of the MemoryNew and MemoryDispose functions) in custom cgi functions (any function that is passed a CGIHdl).
* Process
- 'ProcessIsMoreBusy' and 'ProcessIsLessBusy' will now compile correctly if 'kCompileWithDeferredTask' is not on.
- Modified 'ProcessGiveTime' to take additional parameters 'useWNE' and 'theCGIHdl' (see "ProcessUtil.c" for details). It will now use the 'WSAPI_YieldTime' call when compiling for wsapi. You should always use 'ProcessGiveTime' instead of 'YieldToAnyThread' or other such functions. It will ensure that time is properly allocated to other threads and processes.
- New function 'ProcessPeriodicTask'. This will call the new custom periodic task function 'CustomPeriodicTask'.
- New configuration option: 'kCompileWithPeriodicTask' . Allows you to have tasks processed, outside of CGI events, on a periodic basis.
- New configuration option: 'kSleepTimeForPeriodicTask'. Specifies the amount of time (in ticks) to suggest for inbetween periodic tasks.
* Project Files
- I've separated the 'custom' files from the main 'grantscgi' folder. All the modifiable files are now kept in the "grantscgi projects" folder.
* Quitting
- New function 'QuitWSAPI' handles quitting for WSAPI plug-ins.
* Resources
- The new WebSTAR API (wsapi) reserves all resource numbers between 128 and 9999 inclusive. So, all resources that need to be included in wsapi plug-ins need to be 10000 or higher. Things like dialogs and other interface elements are not affected since they won't be included in plug-ins. Additionally, I'm Grant's CGI Framework reserves resource numbers in the 10000 to 10099 range, leaving users of the framework with numbers from 10100 up.
- The following from "MyCustom.rsrc" changed:
STR#
3000 "HTTP Headers" 10000
3001 "File Names" 10001
3002 "URLs" 10002
TNAM
3002 "LogFileCreator" 10002
- Moved all custom interface related resources (not used for WSAPI plug-ins) from "MyCustom.rsrc" to the new file "MyInterface.rsrc"
* Startup
- New function 'StartupWSAPI' takes the place of 'StartupApplication' when compiling as a WSAPI plug-in.
* Strings
- New functions 'StringCompareNoCase' and 'CharMakeUpper'.
* Windows
- New custom function 'CustomWindowIdle' in "MyHandlers.h" call by 'doIdle' when a custom application window is frontmost.
- 'WindowGrow' has been updated so it now calls the function 'CustomGrowWindow' for any application windows. You can just use the new 'WindowGrowHandler' function from 'CustomGrowWindow' if you want - but if you need custom handling you can now do it.
* Misc
- Fixed the configuration settings in the 'QuitPrepare' function so that thread quitting will compile properly if no threads are preallocated for the application.
- New function 'CustomEmergencyHandler'. Called if some sort of emergency has arisen. What you're basically being asked to do is release any memory, resources, files, etc. that you can.
- By request, "compiler_stuff.h" is now only referenced from within "MyConfiguration.h".
- Added "#pragma unused ()" to functions where appropriate. So, now the "Unused Arguments" warning is turned on in the Codewarrior projects.
